.TH MOTION "9" "" "LinuxCNC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..

.SH NAME
motion \- accepts NML motion commands, interacts with HAL in realtime
.SH SYNOPSIS
\fBloadrt motmod [base_period_nsec=\fIperiod\fB] [base_thread_fp=\fI0 or 1\fB] [servo_period_nsec=\fIperiod\fB] [traj_period_nsec=\fIperiod\fB] [num_joints=\fI[1-16]\fB] [num_dio=\fI[1-64]\fB] [num_aio=\fI[1-64]\fB] [num_spindles=\fI[1-8]\fB]\fR  \fB[unlock_joints_mask=\fR\fIjointmask\fR\fB]\fR \fB[num_extrajoints=\fI[0-16]\fB]\fR

The limits for the following items are compile-time settings:
.TQ
\fBnum_joints\fR: Maximum number of joints is set by EMCMOT_MAX_JOINTS.
.TQ
\fBnum_dio\fR: Maximum number of digital inputs is set by EMCMOT_MAX_DIO.
.TQ
\fBnum_aio\fR: Maximum number of analog inputs is set by EMCMOT_MAX_AIO.
.TQ
\fBnum_spindles\fR: Maximum number of spindles is set by EMCMOT_MAX_SPINDLES

.P
Optionally the number of Digital I/O is set with num_dio. The number of Analog I/O is set with num_aio. The default is 4 each.

.P
Pin names starting with "\fBjoint\fR"  or "\fBaxis\fR" are are read and updated by the motion-controller function.

.SH DESCRIPTION
By default, the base thread does not support floating point.  Software stepping, software encoder counting, and software pwm do not use floating point.  \fBbase_thread_fp\fR can be used to enable floating point in the base thread (for example for brushless DC motor control).

.P
These pins and parameters are created by the realtime \fBmotmod\fR module. This module provides a HAL interface for LinuxCNC's motion planner. Basically \fBmotmod\fR takes in a list of waypoints and generates a nice blended and constraint-limited stream of joint positions to be fed to the motor drives.

.P
The optional \fBnum_extrajoints\fR parameter specifies a quantity of joints
that participate in homing but are not used by kinematics transformations.
After homing, control of an 'extra' joint is transferred to a posthome command
hal pin (joint.N.posthome-cmd) and the motor feedback value is ignored.  'Extra'
joints must be managed by independent motion planners/controllers (typically
using limit3 hal components).  Extra joints maybe unhomed only when motion is
disabled.

The maximum \fBnum_extrajoints\fR value is equal to the \fBnum_joints\fR value.
(Note that using the maximum value would allow no operation in world
coordinates).  The \fBnum_joints\fR value must be equal to the sum of the
number of joints used for kinematics calculations plus the number of 'extra'
joints.

The \fBnum_joints\fR parameter is conventionally set using the ini file
setting \fB[KINS]JOINTS=\fRvalue.  The \fBnum_extrajoints\fR is set by
the additional motmod parameter \fB[EMCMOT]motmod num_extrajoints=\fRvalue.
Hal pin numbering for all joints is zero based [\fB0 ... num_joints-1\fR].
When specified, 'extra' joints are assigned the last \fBnum_extrajoints\fR
in the numbering sequence.  For example, specifying [KINS]JOINTS=5 and
[EMCMOT]motmod num_extrajoints=2 for a 3 joint trivkins configuration
\fB[KINS] KINEMATICS=trivkins coordinates=xyz\fR uses joints 0,1,2 for
the kinematic joints and joints 3,4 for the 'extra' joints.

.SH  MOTION PINS

.TP
\fBmotion-command-handler.time\fR OUT S32
Time (in CPU clocks) for the motion module motion-command-handler

.TP
\fBmotion-controller.time\fR OUT S32
Time (in CPU clocks) for the motion module motion-controller

.TP
\fBmotion.adaptive\-feed\fR IN FLOAT
When adaptive feed is enabled with M52 P1, the commanded velocity is multiplied by this value. This effect is multiplicative with the NML-level feed override value and motion.feed\-hold.
Negative values are valid and will run the G\-code path in reverse.

.TP
\fBmotion.analog\-in\-\fINN\fR IN FLOAT
These pins are used by M66 Enn wait-for-input mode.

.TP
\fBmotion.analog\-out\-\fINN\fR OUT FLOAT
These pins are used by M67-68.

.TP
\fBmotion.coord\-error\fR OUT BIT
TRUE when motion has encountered an error, such as exceeding a soft limit

.TP
\fBmotion.coord\-mode\fR OUT BIT
TRUE when motion is in "coordinated mode", as opposed to "teleop mode"

.TP
\fBmotion.current\-vel\fR OUT FLOAT
Current cartesian velocity

.TP
\fBmotion.digital\-in\-\fINN\fR IN BIT
These pins are used by M66 Pnn wait-for-input mode.

.TP
\fBmotion.digital\-out\-\fINN\fR OUT BIT
These pins are controlled by the M62 through M65 words.

.TP
\fBmotion.distance\-to\-go\fR OUT FLOAT
Distance remaining in the current move

.TP
\fBmotion.enable\fR IN BIT
If this bit is driven FALSE, motion stops, the machine is placed in the "machine off" state, and a message is displayed for the operator. For normal motion, drive this bit TRUE.

.TQ
\fBmotion.eoffset-active\fR OUT BIT
Indicates external offsets are active (non-zero)

.TQ
\fBmotion.eoffset-limited\fR OUT BIT
Indicates motion with external offsets was limited by
a soft limit constraint ([AXIS_L]MIN_LIMIT,MAX_LIMIT).

.TP
\fBmotion.feed\-hold\fR IN BIT
When Feed Stop Control is enabled with M53 P1, and this bit is TRUE, the feed rate is set to 0.

.TP
\fBmotion.feed\-inhibit\fR IN BIT
When this pin is TRUE, machine motion is inhibited (this includes jogs,
programmed feeds, and programmed rapids, aka traverse moves).

If the machine is performing a spindle synchronized move when this
pin goes TRUE, the spindle synchronized motion will finish, and any
following moves will be inhibited (this is to prevent damage to the
machine, the tool, or the work piece).

If the machine is in the middle of a (non-spindle synchronized) move
when this pin goes TRUE, the machine will decelerate to a stop at the
maximum allowed acceleration rate.

Motion resumes when this pin goes FALSE.

.TP
\fBmotion.homing\-inhibit\fR IN BIT
If this bit is TRUE, initiation of any joint homing move (including "Home All")
is disallowed and an error is reported.  By default, homing is allowed in joint
mode whenever motion is enabled.

.TP
\fBmotion.in\-position\fR OUT BIT
TRUE if the machine is in position (ie, not currently moving towards
the commanded position).

.TP
\fBmotion.motion\-enabled\fR OUT BIT

.TP
\fBmotion.motion\-type\fR OUT S32
These values are from src/emc/nml_intf/motion_types.h
.RS
.RS
.TP
0: Idle (no motion)
.P
1: Traverse
.P
2: Linear feed
.P
3: Arc feed
.P
4: Tool change
.P
5: Probing
.P
6: Rotary unlock for traverse
.RE
.RE

.TP
\fBmotion.on\-soft\-limit\fR OUT BIT

.TP
\fBmotion.probe\-input\fR IN BIT
G38.n uses the value on this pin to determine when the probe has made contact. TRUE for probe contact closed (touching), FALSE for probe contact open.

.TP
\fBmotion.program\-line\fR OUT S32
The current program line while executing. Zero if not running or between
lines while single stepping.

.TP
\fBmotion.requested\-vel\fR OUT FLOAT
The current requested velocity in user units per second.  This value is
the F-word setting from the G-code file, possibly reduced to accomodate
machine velocity and acceleration limits. The value on this pin does
not reflect the feed override or any other adjustments.

.TP
\fBmotion.servo.last\-period\fR OUT U32
The number of CPU clocks between invocations of the servo thread. Typically, this number divided by the CPU speed gives the time in seconds, and can be used to determine whether the realtime motion controller is meeting its timing constraints

.TP
\fBmotion.teleop\-mode\fR OUT BIT
Motion mode is teleop (axis coordinate jogging available).

.TQ
\fBmotion.tooloffset.L\fR OUT FLOAT
Current tool offset for each axis where
(\fBL\fR is the axis letter, one of: \fBx y z a b c u v w\fR)

.SH  AXIS PINS
(\fBL\fR is the axis letter, one of: \fBx y z a b c u v w\fR)

.TP
\fBaxis.\fIL\fB.eoffset\fR OUT FLOAT
Current external offset.

.TP
\fBaxis.\fIL\fB.eoffset-clear\fR IN BIT
Clear external offset request

.TP
\fBaxis.\fIL\fB.eoffset-counts\fR IN S32
Counts input for external offset.
The eoffset-counts are transferred to an internal
register.  The applied external offset is the
product of the register counts and the eoffset-scale
value.  The register is \fBreset to zero at each machine
startup\fR.  If the machine is turned off with an external
offset active, the eoffset-counts pin should be set
to zero before restarting.

.TP
\fBaxis.\fIL\fB.eoffset-enable\fR IN BIT
Enable for external offset (also requires ini file
setting for [AXIS_L]OFFSET_AV_RATIO)

.TP
\fBaxis.\fIL\fB.eoffset-request\fR OUT FLOAT
Debug pin for requested external offset.

.TP
\fBaxis.\fIL\fB.eoffset-scale\fR IN FLOAT
Scale for external offset.

.TP
\fBaxis.\fIL\fB.jog\-accel\-fraction\fR IN FLOAT
Sets acceleration for wheel jogging to a fraction of the ini max_acceleration for
the axis. Values greater than 1 or less than zero are ignored.

.TP
\fBaxis.\fIL\fB.jog\-counts\fR IN S32
Connect to the "counts" pin of an external encoder to use a physical jog wheel.

.TP
\fBaxis.\fIL\fB.jog\-enable\fR IN BIT
When TRUE (and in manual mode), any change to "jog\-counts" will result in motion. When false, "jog\-counts" is ignored.

.TP
\fBaxis.\fIL\fB.jog\-scale\fR IN FLOAT
Sets the distance moved for each count on "jog\-counts", in machine units.

.TP
\fBaxis.\fIL\fB.jog\-vel\-mode\fR IN BIT
When FALSE (the default), the jogwheel operates in position mode. The axis will move exactly jog\-scale units for each count, regardless of how long that might take. When TRUE, the wheel operates in velocity mode - motion stops when the wheel stops, even if that means the commanded motion is not completed.

.TP
\fBaxis.\fIL\fB.kb\-jog\-active\fR OUT BIT
(free planner axis jogging active (keyboard or halui))

.TP
\fBaxis.\fIL\fB.pos\-cmd\fR OUT FLOAT
The axis commanded position. There may be several offsets between the axis and motor coordinates: backlash compensation, screw error compensation, and home offsets.  External offsets are reported separately (axis.\fBL\fR.eoffset).

.TP
\fBaxis.\fIL\fB.teleop\-pos\-cmd\fR OUT FLOAT

.TP
\fBaxis.\fIL\fB.teleop\-tp\-enable\fR OUT BIT
TRUE when the "teleop planner" is enabled for this axis

.TP
\fBaxis.\fIL\fB.teleop\-vel\-cmd\fR OUT FLOAT
The axis's commanded velocity

.TP
\fBaxis.\fIL\fB.teleop\-vel\-lim\fR OUT FLOAT
The velocity limit for the teleop planner

.TP
\fBaxis.\fIL\fB.wheel\-jog\-active\fR OUT BIT

.SH JOINT PINS
\fBN\fR is the joint number (\fB0\fR ... \fBnum_joints\-1\fR))
.TP
(\fBNote:\fR pins marked \fB(DEBUG)\fR serve as debugging aids
and are subject to change or removal at any time.)

.TP
\fBjoint.\fIN\fB.joint\-acc\-cmd\fR OUT FLOAT \fB(DEBUG)\fR
The joint's commanded acceleration

.TP
\fBjoint.\fIN\fB.active\fR OUT BIT \fB(DEBUG)\fR
TRUE when this joint is active

.TP
\fBjoint.\fIN\fB.amp\-enable\-out\fR OUT BIT
TRUE if the amplifier for this joint should be enabled

.TP
\fBjoint.\fIN\fB.amp\-fault\-in\fR IN BIT
Should be driven TRUE if an external fault is detected with the amplifier for this joint

.TP
\fBjoint.\fIN\fB.backlash\-corr\fR OUT FLOAT \fB(DEBUG)\fR
Backlash or screw compensation raw value

.TP
\fBjoint.\fIN\fB.backlash\-filt\fR OUT FLOAT \fB(DEBUG)\fR
Backlash or screw compensation filtered value (respecting motion limits)

.TP
\fBjoint.\fIN\fB.backlash\-vel\fR OUT FLOAT \fB(DEBUG)\fR
Backlash or screw compensation velocity

.TP
\fBjoint.\fIN\fB.coarse\-pos\-cmd\fR OUT FLOAT \fB(DEBUG)\fR

.TP
\fBjoint.\fIN\fB.error\fR OUT BIT \fB(DEBUG)\fR
TRUE when this joint has encountered an error, such as a limit switch closing

.TP
\fBjoint.\fIN\fB.f\-error\fR OUT FLOAT \fB(DEBUG)\fR
The actual following error

.TP
\fBjoint.\fIN\fB.f\-error\-lim\fR OUT FLOAT \fB(DEBUG)\fR
The following error limit

.TP
\fBjoint.\fIN\fB.f\-errored\fR OUT BIT \fB(DEBUG)\fR
TRUE when this joint has exceeded the following error limit

.TP
\fBjoint.\fIN\fB.faulted\fR OUT BIT \fB(DEBUG)\fR

.TP
\fBjoint.\fIN\fB.free\-pos\-cmd\fR OUT FLOAT \fB(DEBUG)\fR
The "free planner" commanded position for this joint.

.TP
\fBjoint.\fIN\fB.free\-tp\-enable\fR OUT BIT \fB(DEBUG)\fR
TRUE when the "free planner" is enabled for this joint

.TP
\fBjoint.\fIN\fB.free\-vel\-lim\fR OUT FLOAT \fB(DEBUG)\fR
The velocity limit for the free planner

.TP
\fBjoint.\fIN\fB.home\-state\fR OUT S32 \fB(DEBUG)\fR
homing state machine state

.TP
\fBjoint.\fIN\fB.home\-sw\-in\fR IN BIT
Should be driven TRUE if the home switch for this joint is closed

.TP
\fBjoint.\fIN\fB.homed\fR OUT BIT \fB(DEBUG)\fR
TRUE if the joint has been homed

.TP
\fBjoint.\fIN\fB.homing\fR OUT BIT
TRUE if the joint is currently homing

.TP
\fBjoint.\fIN\fB.in\-position\fR OUT BIT \fB(DEBUG)\fR
TRUE if the joint is using the "free planner" and has come to a stop

.TP
\fBjoint.\fIN\fB.index\-enable\fR IO BIT
Should be attached to the index\-enable pin of the joint's encoder to enable homing to index pulse

.TQ
\fBjoint.N.is\-unlocked\fR IN BIT
Indicates joint is unlocked (see JOINT UNLOCK PINS).

.TP
\fBjoint.\fIN\fB.jog\-accel\-fraction\fR IN FLOAT
Sets acceleration for wheel jogging to a fraction of the ini max_acceleration for
the joint.  Values greater than 1 or less than zero are ignored.

.TP
\fBjoint.\fIN\fB.jog\-counts\fR IN S32
Connect to the "counts" pin of an external encoder to use a physical jog wheel.

.TP
\fBjoint.\fIN\fB.jog\-enable\fR IN BIT
When TRUE (and in manual mode), any change to "jog\-counts" will result in motion. When false, "jog\-counts" is ignored.

.TP
\fBjoint.\fIN\fB.jog\-scale\fR IN FLOAT
Sets the distance moved for each count on "jog\-counts", in machine units.

.TP
\fBjoint.\fIN\fB.jog\-vel\-mode\fR IN BIT
When FALSE (the default), the jogwheel operates in position mode. The joint will move exactly jog\-scale units for each count, regardless of how long that might take. When TRUE, the wheel operates in velocity mode - motion stops when the wheel stops, even if that means the commanded motion is not completed.

.TP
\fBjoint.\fIN\fB.kb\-jog\-active\fR OUT BIT \fB(DEBUG)\fR
(free planner joint jogging active (keyboard or halui))

.TP
\fBjoint.\fIN\fB.motor\-offset\fR OUT FLOAT \fB(DEBUG)\fR
joint motor offset established when joint is homed.

.TP
\fBjoint.\fIN\fB.motor\-pos\-cmd\fR OUT FLOAT
The commanded position for this joint.

.TP
\fBjoint.\fIN\fB.motor\-pos\-fb\fR IN FLOAT
The actual position for this joint.

.TP
\fBjoint.\fIN\fB.neg\-hard\-limit\fR OUT BIT \fB(DEBUG)\fR
The negative hard limit for the joint

.TP
\fBjoint.\fIN\fB.neg\-lim\-sw\-in\fR IN BIT
Should be driven TRUE if the negative limit switch for this joint is tripped.

.TP
\fBjoint.\fIN\fB.pos\-cmd\fR OUT FLOAT
The joint (as opposed to motor) commanded position. There may be several offsets between the joint and motor coordinates: backlash compensation, screw error compensation, and home offsets.

.TP
\fBjoint.\fIN\fB.pos\-fb\fR OUT FLOAT
The joint feedback position. This value is computed from the actual motor position minus joint offsets. Useful for machine visualization.

.TP
\fBjoint.\fIN\fB.pos\-hard\-limit\fR OUT BIT \fB(DEBUG)\fR
The positive hard limit for the joint

.TP
\fBjoint.\fIN\fB.pos\-lim\-sw\-in\fR IN BIT
Should be driven TRUE if the positive limit switch for this joint is tripped.

.TP
\fBjoint.\fIN\fB.unlock\fR OUT BIT
TRUE if the axis is a locked joint (typically a rotary) and a move
is commanded (see JOINT UNLOCK PINS).

.TP
\fBjoint.\fIN\fB.joint\-vel\-cmd\fR OUT FLOAT \fB(DEBUG)\fR
The joint's commanded velocity

.TP
\fBjoint.\fIN\fB.wheel\-jog\-active\fR OUT BIT \fB(DEBUG)\fR

.SH JOINT posthome pins
Each joint designated as an 'extra' joint is provided with a hal pin
\fBjoint.N.posthome-cmd\fR.  The pin value is ignored prior to homing.
After homing, the pin value is augmented by the motor offset value
and routed to the \fBjoint.N.motor-pos-cmd\fR.

.SH JOINT unlock pins
The joint pins used for unlocking a joint
(\fBjoint.N.unlock\fR, \fBjoint.N.is-unlocked\fR),
are created according to the \fBunlock_joints_mask=\fRjointmask parameter for motmod.  These pins may be required for locking indexers (typically a rotary joint)

The jointmask bits are: (lsb)0:joint0, 1:joint1, 2:joint2, ...

.TQ
Example: loadrt motmod ... \fBunlock_joints_mask=\fR0x38 creates unlock pins for joints 3,4,5

.SH  SPINDLE PINS
(\fBM\fR is the spindle number (\fB0\fR ... \fBnum_spindles\-1\fR))

.TP
\fBspindle.M\fB.amp\-fault\-in\fR IN BIT
Should be driven TRUE if an external fault is detected with the amplifier for this spindle

.TP
\fBspindle.M.at\-speed\fR IN BIT
Motion will pause until this pin is TRUE, under the following conditions: before the
first feed move after each spindle start or speed change; before the start of every
chain of spindle\-synchronized moves; and if in CSS mode, at every rapid\->feed transition.

.TP
\fBspindle.M.brake\fR OUT BIT
TRUE when the spindle brake should be applied

.TP
\fBspindle.M.forward\fR OUT BIT
TRUE when the spindle should rotate forward

.TP
\fBspindle.M.index\-enable\fR I/O BIT
For correct operation of spindle synchronized moves, this signal must be hooked to the index\-enable pin of the spindle encoder.

.TP
\fBspindle.M.inhibit\fR IN BIT
When TRUE, the spindle speed is set and held to 0.

.TP
\fBspindle.M.is\-oriented\fR IN BIT
Acknowledge pin for spindle\-orient. Completes orient cycle. If spindle\-orient was true when spindle\-is\-oriented
was asserted, the spindle\-orient pin is cleared and the spindle\-locked pin is asserted. Also, the spindle\-brake pin is asserted.

.TP
\fBspindle.M.locked\fR OUT BIT
Spindle orient complete pin. Cleared by any of M3,M4,M5.

.TP
\fBspindle.M.on\fR OUT BIT
TRUE when spindle should rotate

.TP
\fBspindle.M.orient\fR OUT BIT
Indicates start of spindle orient cycle. Set by M19. Cleared by any of M3,M4,M5.

If spindle\-orient\-fault is not zero during spindle\-orient true, the M19 command fails with an error message.

.TP
\fBspindle.M.orient\-angle\fR OUT FLOAT
Desired spindle orientation for M19. Value of the M19 R word parameter plus the value of the [RS274NGC]ORIENT_OFFSET ini parameter.

.TP
\fBspindle.M.orient\-fault\fR IN S32
Fault code input for orient cycle. Any value other than zero will cause the orient cycle to abort.

.TP
\fBspindle.M.orient\-mode\fR OUT BIT
Desired spindle rotation mode. Reflects M19 P parameter word.

.TP
\fBspindle.M.reverse\fR OUT BIT
TRUE when the spindle should rotate backward

.TP
\fBspindle.M.revs\fR IN FLOAT
For correct operation of spindle synchronized moves, this signal must be hooked to the position pin of the spindle encoder.

.TP
\fBspindle.M.speed\-cmd\-rps\fR FLOAT OUT
Commanded spindle speed in units of revolutions per second

.TP
\fBspindle.M.speed\-in\fR IN FLOAT
Actual spindle speed feedback in revolutions per second; used for G96 (constant surface speed) and G95 (feed per revolution) modes.

.TP
\fBspindle.M.speed\-out\fR OUT FLOAT
Desired spindle speed in rotations per minute

.TP
\fBspindle.M.speed\-out\-abs\fR OUT FLOAT
Desired spindle speed in rotations per minute, always positive regardless of spindle direction.

.TP
\fBspindle.M.speed\-out\-rps\fR OUT FLOAT
Desired spindle speed in rotations per second

.TP
\fBspindle.M.speed\-out\-rps\-abs\fR OUT FLOAT
Desired spindle speed in rotations per second, always positive regardless of spindle direction.

.SH MOTION PARAMETERS

Many of the parameters serve as debugging aids, and are subject to change or removal at any time.

.TQ
\fBmotion\-command\-handler.tmax\fR RW S32
Show information about the execution time of these HAL functions in CPU clocks

.TQ
\fBmotion\-command\-handler.tmax\-increased\fR RO S32

.TQ
\fBmotion\-controller.tmax\fR RW S32
Show information about the execution time of these HAL functions in CPU clocks

.TQ
\fBmotion\-controller.tmax\-increased\fR RO BIT

.TP
\fBmotion.debug\-\fI*\fR
These values are used for debugging purposes.

.SH FUNCTIONS

Generally, these functions are both added to the servo-thread in the order shown.

.TP
\fBmotion\-command\-handler\fR
Processes motion commands coming from user space.
The pin named \fBmotion-command-handler.time\fR and parameters
\fBmotion-command-handler.tmax,tmax-increased\fRare created for
this function.

.TP
\fBmotion\-controller\fR
Runs the LinuxCNC motion controller
The pin named \fBmotion-controller.time\fR and parameters
\fBmotion-controller.tmax,tmax-increased\fR are created for
this function.

.SH BUGS
This manual page is incomplete.
.TQ
Identification of pins categorized with \fB(DEBUG)\fR is dubious.

.SH SEE ALSO
iocontrol(1), milltask(1)
